DOC: Added examples to pandas.concat documentation #15028

palewire · 2017-01-01T02:20:26Z

I've added two simple examples to the pd.concat documentation. I've also done a very small amount of clean up on the rest of the docstring.

passes git diff upstream/master | flake8 --diff

jreback · 2017-01-01T18:46:21Z

pandas/tools/merge.py

    Returns
    -------
    concatenated : type of objects
+
+    Notes
+    -----


if you are going to add examples, then this needs to be more complete, using examples from here:http://pandas.pydata.org/pandas-docs/stable/merging.html#concatenating-objects

certainly not all of these, but a quick selection (as well as having this link would be fine).

palewire · 2017-01-01T19:34:10Z

That's fine by me. I'll add a link to that walkthrough and a wider array of examples. I'll aim for the new examples to be more discrete and less holistic than the walkthrough.

…

On Sun, Jan 1, 2017, 10:46 AM Jeff Reback ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In pandas/tools/merge.py <#15028 (review)> : > Returns ------- concatenated : type of objects + + Notes + ----- if you are going to add examples, then this needs to be more complete, using examples from here: http://pandas.pydata.org/pandas-docs/stable/merging.html#concatenating-objects certainly not all of these, but a quick selection (as well as having this link would be fine). — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#15028 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAnCTODtT334eXdmY1T9r-nH2TZjBXOks5rN_SGgaJpZM4LYpwL> .

jorisvandenbossche · 2017-01-02T08:13:29Z

pandas/tools/merge.py

+    Combine two ``Series``.
+
+        >>> import pandas as pd
+        >>> s1 = pd.Series(['a', 'b'])


no indentation is needed here for the example blocks

(and the 'import pandas as pd' can also be left out -> this is assumed)

jreback · 2017-01-02T16:28:27Z

pandas/tools/merge.py

@@ -705,7 +705,7 @@ def _get_join_info(self):
                _left_join_on_index(left_ax, right_ax, self.left_join_keys,
                                    sort=self.sort)

-        elif self.left_index and self.how == 'right':
+        elif self.tleft_index and self.how == 'right':


pls don't change code in the same PR as docs (unless its germane), I assume this was a typo though.

It was. I'm sorry for the oversight.

jorisvandenbossche

Nice examples! Added some more comments

jorisvandenbossche · 2017-01-02T20:05:08Z

pandas/tools/merge.py

+    3    d
+    dtype: object
+
+    Add a ``hierarchical index`` at the outermost level of


no need to add backtick quotes around 'hierarchical index'

I've fixed this.

jorisvandenbossche · 2017-01-02T20:07:29Z

pandas/tools/merge.py

+        1    d
+        2    e
+    dtype: object
+    >>> c.ix['s1']


The above example is good. But I would leave out the examples on indexing the result to keep the examples focused on concat (such examples would certainly be nice for the tutorial docs)

Maybe add an example with axis=1

I've removed the ix calls and added axis=1 to my list for later.

jorisvandenbossche · 2017-01-02T20:07:52Z

pandas/tools/merge.py

+
+    >>> s1 = pd.Series(['a', 'b', 'c'])
+    >>> s2 = pd.Series(['c', 'd', 'e'])
+    >>> c = pd.concat([s1, s2], keys=["s1", 's2',])


can you use consistent quotes within the keys list (eg always single quotes)?

I've fixed this.

…ndex example

codecov-io · 2017-01-03T03:12:08Z

Current coverage is 84.75% (diff: 100%)

Merging #15028 into master will decrease coverage by 0.01%

@@             master     #15028   diff @@
==========================================
  Files           145        145          
  Lines         51131      51146    +15   
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
+ Hits          43345      43350     +5   
- Misses         7786       7796    +10   
  Partials          0          0

Powered by Codecov. Last update 3662413...c58f9f8

palewire · 2017-01-03T16:58:11Z

@jorisvandenbossche and @jreback, I believe I've made the changes you've asked for. Please let me know if there's anything more I can do.

jorisvandenbossche

Some stylistic comments on the examples you added.

jorisvandenbossche · 2017-01-03T20:36:40Z

pandas/tools/merge.py

+    by setting the ``ignore_index`` option to ``True``.
+
+    >>> s1 = pd.Series(['a', 'b'])
+    >>> s2 = pd.Series(['c', 'd'])


Can you leave out the redefinition of s1 and s2 ? (to save some vertical space) We can assume that the example build on each other.

I will make this change and push it shortly.

jorisvandenbossche · 2017-01-03T20:37:17Z

pandas/tools/merge.py

+    the data with the ``keys`` option.
+
+    >>> s1 = pd.Series(['a', 'b', 'c'])
+    >>> s2 = pd.Series(['c', 'd', 'e'])


Here as well (you can use the same s1 and s2 I think)

Change coming.

jorisvandenbossche · 2017-01-03T20:39:07Z

pandas/tools/merge.py

+    ...     [s1, s2],
+    ...     keys=['s1', 's2',],
+    ...     names=['Series name', 'Row ID']
+    ... )


Style-wise, can you do

pd.concat([s1, s2], keys=[...], names=[...])

to have a more consistent style within the docs

Will do. I was unaware that was the established style.

No, no problem. We don't have this documented clearly what is expected here (and are not always that consistent in existing docs)

jorisvandenbossche · 2017-01-03T20:39:23Z

pandas/tools/merge.py

+    >>> df1 = pd.DataFrame(
+    ...     [['a', 1], ['b', 2]],
+    ...     columns=['letter', 'number']
+    ... )


the same here regarding style

jorisvandenbossche · 2017-01-03T20:40:22Z

pandas/tools/merge.py

+    >>> df2 = pd.DataFrame(
+    ...     [['c', 3, 'cat'], ['d', 4, 'dog']],
+    ...     columns=['letter', 'number', 'animal']
+    ... )


also here, I would leave out the redefinition and display of the same dataframes (then what is shown is more focused on the result)

I meant this comment actually for the example below, as here df2 is actually changed (maybe only show df2 creation and display in this example)

jorisvandenbossche · 2017-01-03T20:42:58Z

pandas/tools/merge.py

+    1      b       2
+    >>> df2 = pd.DataFrame(
+    ...     [['c', 3], ['d', 4]],
+    ...     columns=['letter', 'number']


I would use here eg the 'animal' column name to have different columns (that is IMO a more natural example to concat columns with different names)

palewire · 2017-01-03T23:28:06Z

@jorisvandenbossche I believe I have made the changes you've requested. Please let me know if there's more I can do.

jorisvandenbossche · 2017-01-04T13:51:41Z

@palewire Thanks!

DOC: Added examples to pandas.concat documentation

6c916a9

jreback reviewed Jan 1, 2017

View reviewed changes

jreback added the Docs label Jan 1, 2017

jorisvandenbossche reviewed Jan 2, 2017

View reviewed changes

palewire added 2 commits January 2, 2017 08:24

Added ignore_index example

67a750c

Removed pandas import from example

2e85990

jreback reviewed Jan 2, 2017

View reviewed changes

palewire added 2 commits January 2, 2017 08:30

Wording change

709ec27

Added keys example

afa7502

jorisvandenbossche reviewed Jan 2, 2017

View reviewed changes

palewire added 7 commits January 2, 2017 12:14

Added names options

3887774

Make some fixes for @jorisvandenbossche

415f082

Removed typo

40ccf8b

Added a simple axis=1 example

2d83cd6

An example with a gap is probably better

76a9814

Added join examples

16b8d28

Added link to walkthrough, some see also links as well as an verify i…

f005280

…ndex example

Cleaned up axis example

7c5126f

jorisvandenbossche reviewed Jan 3, 2017

View reviewed changes

Changes to concat docs

5141b46

palewire and others added 2 commits January 3, 2017 15:30

Corrected indentation

c58f9f8

correct link to tutorial docs

780d206

jorisvandenbossche merged commit 7c0b4a3 into pandas-dev:master Jan 4, 2017

jorisvandenbossche added this to the 0.20.0 milestone Jan 4, 2017

Uh oh!

DOC: Added examples to pandas.concat documentation #15028

DOC: Added examples to pandas.concat documentation #15028

Uh oh!

Conversation

palewire commented Jan 1, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

palewire commented Jan 1, 2017 via email

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov-io commented Jan 3, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Current coverage is 84.75% (diff: 100%)

Uh oh!

palewire commented Jan 3, 2017

Uh oh!

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

palewire commented Jan 3, 2017

Uh oh!

jorisvandenbossche commented Jan 4, 2017

Uh oh!

Uh oh!

codecov-io commented Jan 3, 2017 •

edited

Loading